<!DOCTYPE html><html><head><meta charset=utf-8><title>H3DU.Surface</title></head><body><h1> H3DU.Surface</h1><p><a href='index.html'>Back to documentation index.</a></p><a name='H3DU.Surface'></a>
<h3> H3DU.Surface(surface)</h3>A surface evaluator object for a parametric surface.<p>
A parametric surface is a surface whose points are based on a
parametric surface function. A surface function takes two numbers
(U and V) and returns a point (in 1, 2, 3 or more dimensions, but
usually 2 or 3) that lies on the surface. For example, in 3
dimensions, a surface function has the following form:<p>
<b>F</b>(u, v) = [ x(u, v), y(u, v), z(u, v) ]<p>
where x(u, v) returns an X coordinate, y(u, v) a Y coordinate,
and z(u, v) returns a Z coordinate.<p>
Specialized surfaces should <a href="tutorial-subclass.html">subclass</a> this class and implement
the <code>evaluate</code> method and, optionally, the other methods mentioned in the "surface" parameter below.<h4> Parameters</h4><ul><li><code>surface</code> (Type: Object)<br>A <b>surface evaluator object</b>, which is an object that must contain an <code>evaluate</code> method and may contain an <code>endPoints</code>, <code>tangent</code>, <code>bitangent</code>, and/or <code>gradient</code> method, as described in the corresponding methods of this class.</ul><h4> Example</h4><p>The following example creates a surface evaluator
object for a parametric surface. To illustrate how the gradient method is derived
from the vector calculation method, that method is also given below. To
derive the normal calculation, first look at the vector function:<p>
<b>F</b>(u, v) = (cos(u), sin(u), sin(u)*cos(v))<p>
Then, find the partial derivatives with respect to <i>u</i> and to <i>v</i>:<p>
&#x2202;<b>F</b>/&#x2202;<i>u</i> = (-sin(u), cos(u), cos(u)*cos(v))<br>
&#x2202;<b>F</b>/&#x2202;<i>v</i> = (0, 0, -sin(v)*sin(u))<p>
Next, take their cross product:<p>
<b>c</b>(u, v) = (-sin(v)*cos(u)*sin(u), -sin(v)*sin(u)*sin(u), 0)<br><p>
The result is the gradient, which will be normal to the surface.
</p><pre>
var surface=new H3DU.Surface({"evaluate":function(u,v) {
"use strict";
return [Math.cos(u),Math.sin(u),Math.sin(u)*Math.cos(v)];
},
"gradient":function(u,v) {
"use strict";
return [
Math.cos(u)*-Math.sin(v)*Math.sin(u),
Math.sin(u)*-Math.sin(v)*Math.sin(u),
0];
}})</pre><h3> Methods</h3><ul><li><a href='#H3DU.Surface_bitangent'>bitangent</a><br>Finds an approximate bitangent vector of this surface at the given U and V coordinates.<li><a href='#H3DU.Surface_endPoints'>endPoints</a><br>Returns the starting and ending U and V coordinates of this surface.<li><a href='#H3DU.Surface_evaluate'>evaluate</a><br>Finds the position of this surface at the given U and V coordinates.<li><a href='#H3DU.Surface_gradient'>gradient</a><br>Finds an approximate gradient vector of this surface at the given U and V coordinates.<li><a href='#H3DU.Surface_normal'>normal</a><br>Convenience method for finding an approximate normal vector of this surface at the given U and V coordinates.<li><a href='#H3DU.Surface_tangent'>tangent</a><br>Finds an approximate tangent vector of this surface at the given U and V coordinates.</ul><a name='H3DU.Surface_bitangent'></a>
<h3> H3DU.Surface#bitangent(u, v)</h3>Finds an approximate bitangent vector of this surface at the given U and V coordinates.<p>
The implementation in <a href="H3DU.Surface.html">H3DU.Surface</a> calls the evaluator's <code>bitangent</code>
method if it implements it; otherwise, does a numerical differentiation
with respect to the V axis using the <code>evaluate</code> method.<p>
The <b>bitangent vector</b> is the vector pointing in the direction of the V axis, or alternatively,
the partial derivative of the <code>evaluate</code> method with respect to <code>v</code>. The bitangent vector returned by this method <i>should not</i> be "normalized" to a <a href="tutorial-glmath.html">unit vector</a>.<h4> Parameters</h4><ul><li><code>u</code> (Type: number)<br>U coordinate of a point on the surface.<li><code>v</code> (Type: number)<br>V coordinate of a point on the surface.</ul><h4> Return Value</h4>An array describing a bitangent vector. It should have at least as many
elements as the number of dimensions of the underlying surface. (Type: Array.&lt;number>)<a name='H3DU.Surface_endPoints'></a>
<h3> H3DU.Surface#endPoints()</h3>Returns the starting and ending U and V coordinates of this surface.
This method calls the evaluator's <code>endPoints</code>
method if it implements it; otherwise, returns <code>[0, 1, 0, 1]</code><h4> Return Value</h4>A four-element array. The first and second
elements are the starting and ending U coordinates, respectively, of the surface, and the third
and fourth elements are its starting and ending V coordinates.
Returns <code>[0, 1, 0, 1]</code> if the evaluator doesn't implement an <code>endPoints</code>
method.<a name='H3DU.Surface_evaluate'></a>
<h3> H3DU.Surface#evaluate(u, v)</h3>Finds the position of this surface at the given U and V coordinates.<h4> Parameters</h4><ul><li><code>u</code> (Type: number)<br>U coordinate of a point on the surface.<li><code>v</code> (Type: number)<br>V coordinate of a point on the surface.</ul><h4> Return Value</h4>An array describing a position. It should have at least as many
elements as the number of dimensions of the underlying surface. (Type: Array.&lt;number>)<a name='H3DU.Surface_gradient'></a>
<h3> H3DU.Surface#gradient(u, v)</h3>Finds an approximate gradient vector of this surface at the given U and V coordinates.<p>
The implementation in <a href="H3DU.Surface.html">H3DU.Surface</a> calls the evaluator's <code>gradient</code>
method if it implements it; otherwise uses the surface's tangent and bitangent vectors to implement the gradient
(however, this approach is generally only meaningful for a three-dimensional surface).<p>
The <b>gradient</b> is a vector pointing up and away from the surface.
If the evaluator describes a regular three-dimensional surface (usually
a continuous, unbroken surface such as a sphere, an open
cylinder, or a disk rotated in three dimensions), this can be the cross product
of the <a href="H3DU.Surface.html#H3DU.Surface_tangent">tangent vector</a>
and <a href="H3DU.Surface.html#H3DU.Surface_bitangent">bitangent vector</a>,
in that order. The gradient returned by this method <i>should not</i> be "normalized" to a <a href="tutorial-glmath.html">unit vector</a>.<h4> Parameters</h4><ul><li><code>u</code> (Type: number)<br>U coordinate of a point on the surface.<li><code>v</code> (Type: number)<br>V coordinate of a point on the surface.</ul><h4> Return Value</h4>An array describing a gradient vector. It should have at least as many
elements as the number of dimensions of the underlying surface. (Type: Array.&lt;number>)<a name='H3DU.Surface_normal'></a>
<h3> H3DU.Surface#normal(u, v)</h3>Convenience method for finding an approximate normal vector of this surface at the given U and V coordinates.
The <b>normal vector</b> is the same as the gradient vector, but "normalized" to a unit vector.<h4> Parameters</h4><ul><li><code>u</code> (Type: number)<br>U coordinate of a point on the surface.<li><code>v</code> (Type: number)<br>V coordinate of a point on the surface.</ul><h4> Return Value</h4>An array describing a normal vector. It should have at least as many
elements as the number of dimensions of the underlying surface. (Type: Array.&lt;number>)<a name='H3DU.Surface_tangent'></a>
<h3> H3DU.Surface#tangent(u, v)</h3>Finds an approximate tangent vector of this surface at the given U and V coordinates.
The implementation in <a href="H3DU.Surface.html">H3DU.Surface</a> calls the evaluator's <code>tangent</code>
method if it implements it; otherwise, does a numerical differentiation
with respect to the U axis using the <code>evaluate</code> method.<p>
The <b>tangent vector</b> is the vector pointing in the direction of the U axis,
or alternatively, the partial derivative of the <code>evaluate</code> method with respect to <code>u</code>.
The tangent vector returned by this method <i>should not</i> be "normalized" to a <a href="tutorial-glmath.html">unit vector</a>.<h4> Parameters</h4><ul><li><code>u</code> (Type: number)<br>U coordinate of a point on the surface.<li><code>v</code> (Type: number)<br>V coordinate of a point on the surface.</ul><h4> Return Value</h4>An array describing a tangent vector. It should have at least as many
elements as the number of dimensions of the underlying surface. (Type: Array.&lt;number>)<p><a href='index.html'>Back to documentation index.</a></p></body></html>
